/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.util.evaluators;

import com.hercules.android.receiver.AndroidReceiver;

/**
 * <p>
 * This interface represents a path evaluator that defines methods for retrieving IDs of XRE objects by their DOM
 * paths.
 * </p>
 *
 * <p>
 * <strong>Thread Safety: </strong> Implementations of this interface are not required to be thread safe.
 * </p>
 *
 * @author saarixx, sparemax
 * @version 1.0
 */
public interface PathEvaluator {
    /**
     * <p>
     * Evaluates the given XRE object DOM path.
     * </p>
     *
     * @param path
     *            the DOM path to be evaluated.
     * @param sourceId
     *            the ID of the source XRE object.
     * @param receiver
     *            the Android receiver.
     *
     * @return the retrieved target XRE object ID.
     *
     * @throws IllegalArgumentException
     *             if path is <code>null</code>/empty, sourceId is not positive or receiver is <code>null</code>.
     * @throws InvalidAndroidReceiverStateException
     *             if the provided receiver or some XRE object was not properly initialized.
     * @throws InvalidPathException
     *             if the provided XRE object path is invalid.
     */
    public int evaluatePath(String path, int sourceId, AndroidReceiver receiver)
        throws InvalidAndroidReceiverStateException, InvalidPathException;

    /**
     * <p>
     * Evaluates the given XRE object DOM path. Allows to specify whether custom ID prefixes in format "$id." can be
     * evaluated.
     * </p>
     *
     * @param path
     *            the DOM path to be evaluated.
     * @param sourceId
     *            the ID of the source XRE object.
     * @param receiver
     *            the Android receiver.
     * @param supportCustomId
     *            <code>true</code> if custom root XRE object IDs must be supported; <code>false</code> otherwise.
     *
     * @return the retrieved target XRE object ID.
     *
     * @throws IllegalArgumentException
     *             if path is <code>null</code>/empty, sourceId is not positive or receiver is <code>null</code>.
     * @throws InvalidAndroidReceiverStateException
     *             if the provided receiver or some XRE object was not properly initialized.
     * @throws InvalidPathException
     *             if the provided XRE object path is invalid.
     */
    public int evaluatePath(String path, int sourceId, AndroidReceiver receiver, boolean supportCustomId)
        throws InvalidAndroidReceiverStateException, InvalidPathException;
}
